.so ../bk-macros
.TH "bk annotate" "\*[BKVER]" %E% "\*(BC" "\*(UM"
.SH NAME
bk annotate \- provide annotated listings of one or more source files
.SH SYNOPSIS
.B bk annotate [\fIoptions\fP] 
.BKARGS
.SH DESCRIPTION
.LP
\*[BK] annotations add an extra level of information, such as date, author,
etc., when viewing file contents.
Annotated listings are useful for deeper understanding of your source
base, i.e., when you are tracking down bugs.  
.LP
\*(BK has two kinds of annotations: annotations of a specific version of a file,
and annotations of all (or some) versions of a file
(the second form is unique to \*(BK).
.LP
By default, the
.B bk annotate
command will display a specific version of a file with annotations. 
The default version of file is the most recent version; the 
.Q \-r
option may be used to specify an alternative version.
The default annotations are the revision in which the change was
made and the user who made that change.  
Selecting any annotations overrides all of the default annotations.
.LP
An alternate form of the
.B bk annotate
command may be used to show or annotate either all lines added by
all versions or just the lines added by one or more versions (in
the latter case, the whole file is not displayed, instead, only
the lines which were added in that range of changes are
displayed.)
The
.Q \-R
option turns on this form of annotation.
Each version of a line is grouped closely with other versions of
that line.
This can be useful for determining when a particular feature was
added or modified.
This form of annotation has no annotations by default; the desired
annotations must be specified.
If no annotations are specified then the selected lines are shown
without annotations.
.SH OPTIONS
.TP \-A\*<bdnpru\*>
.OPTreq \-A 5dnpru
Align annotations in a human readable form.
The set of annotations will be followed by a vertical bar and a space
before the data from each line of the file starts.
Each annotation is aligned in a column.
The option argument[s] turn on one
or more annotations as a prefix to each line.
The order of annotations is fixed (no matter what order you 
specify them) and is the same as the order listed below:
.RS
.tp
.B p
Prefix each line with the pathname of the file relative to the current working
directory.
The name is always the current name of the file even if it has been renamed.
.tp
.B d
Prefix each line with the date of last modification.
.tp
.B u
Prefix each line with the name of the user who last modified it.
.tp
.B r
Prefix each line with the revision of the last modification.
.tp
.B 5
Prefix each line with the MD5 key of the last modification.
.tp
.B n
Prefix each line with its line number.
.RE
.tp
.OPTreq \-a 5dnpru
Similar to
.Q \-A 
but without the alignment (each annotation is followed by a tab).
The order of fields is fixed and is:
pathname, date, user, revision, md5key, line number.
.tp
.OPTreq \-c dates
annotate only the lines added by the specified range of dates.
See
.B bk range
for information on specifying dates.
.tp
.B \-k
do not expand RCS or SCCS keywords.
This option is implied by
.QR \-c 
and
.QR \-R .
.tp
.OPTreq \-r rev
annotate all lines in this version of the file.
.tp
.OPTopt \-R rev
annotate only the lines added by the specified revision (or range of revisions).
If
.ARG rev
is not specified, that implies all revisions (i.e.,
\*(lq\fB.\|.\fP\*(rq).
The difference between this option and the previous option
is that in this case
.B bk annotate
shows only those lines 
.B added
by the specified revision[s], but in the 
.Q \-r
case, the entire contents of the specified version is annotated.
.tp
.OPTopt \-w rev
Change the format of the
.QR r
annotation from
.QR rev
to
.QR rev\-d\<rev\>
in the case where the line is deleted from the rev passed as the
argument, or
.QR rev-x\<rev\>
in the case where the line has been excluded.
If no rev argument is given, the tip revision is used.
.SH EXAMPLES
Annotate the latest revision of a file:
.DS
$ bk annotate foo.c
.DE
Annotate the lines added in the latest revision of that file
.DS
$ bk annotate -R+ foo.c
.DE
Annotate all lines in all versions of that file
.DS
$ bk annotate -R foo.c
.DE
Annotate all lines added to all files in the current directory 
between June 1 of 2010 and July 31 of 2010:
.DS
$ bk annotate -c2010/06..2010/07
.DE
To annotate all lines added between two tagged releases:
.DS
bk -U annotate -Rbk-4.6..bk-5.0
.DE
.SH NOTES
In previous versions of BitKeeper, the
.Q \-c
option was used to select a single revision and annotate all lines in that 
revision.
You can now get the same effect as the old:
.DS
bk annotate -c2000 foo.c
.DE
with the more complicated (this assumes bash is your shell):
.DS
bk annotate -r$(bk prs -1 -hnd:REV: -c..2000 foo.c) foo.c
.DE
.SH SEE ALSO
.LP
.SA co
.SA grep
.SA range
.SA revtool
.\" help://blame
.\" help://sccscat
.\" help://bk-sccscat
.\" help://sccscat.1
.\" help://bk-sccscat.1
.SH CATEGORY
.B File
